package com.xhj.mybatis.executor;

import com.xhj.mybatis.cache.CacheKey;
import com.xhj.mybatis.mapping.BoundSql;
import com.xhj.mybatis.mapping.MappedStatement;
import com.xhj.mybatis.session.ResultHandler;
import com.xhj.mybatis.session.RowBounds;
import com.xhj.mybatis.transaction.Transaction;

import java.sql.SQLException;
import java.util.List;

/**
 * Executor
 *
 * @author XJks
 * @description 执行器接口
 */
public interface Executor {

    /**
     * 定义一个常量，表示没有结果处理器（ResultHandler），通常用于不需要特殊处理结果的场景
     */
    ResultHandler NO_RESULT_HANDLER = null;

    /**
     * 执行更新操作（如INSERT、UPDATE、DELETE），返回受影响的行数
     */
    int update(MappedStatement ms, Object parameter) throws SQLException;

    /**
     * 执行查询操作，返回结果列表
     */
    <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler, CacheKey cacheKey, BoundSql boundSql) throws SQLException;

    /**
     * 执行查询操作，返回结果列表
     */
    <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) throws SQLException;

    /**
     * 提交事务，如果required为true则必须提交
     */
    void commit(boolean required) throws SQLException;

    /**
     * 回滚事务，如果required为true则必须回滚
     */
    void rollback(boolean required) throws SQLException;

    /**
     * 创建一个缓存键，用于唯一标识某个查询结果，便于缓存管理
     */
    CacheKey createCacheKey(MappedStatement ms, Object parameterObject, RowBounds rowBounds, BoundSql boundSql);

    /**
     * 判断某个查询是否已经被缓存
     */
    boolean isCached(MappedStatement ms, CacheKey key);

    /**
     * 清除本地缓存，通常在执行更新操作后调用，防止脏读
     */
    void clearLocalCache();

    /**
     * 获取当前的事务对象，用于管理数据库事务
     */
    Transaction getTransaction();

    /**
     * 关闭执行器，forceRollback为true时强制回滚事务
     */
    void close(boolean forceRollback);

    /**
     * 设置执行器的包装器，用于装饰或增强执行器功能
     */
    void setExecutorWrapper(Executor executor);
}
